/*
 * Copyright (C) 2012-2013  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.remote.rsa.message.transport;

import java.rmi.RemoteException;
import java.util.concurrent.TimeUnit;

import nemos.remote.rsa.message.data.InvocationMessage;
import nemos.remote.rsa.message.data.Message;
import nemos.remote.rsa.message.data.ResponseMessage;
import nemos.util.BlockingReference;

/**
 * ITransport : The message transport service interface.
 * 
 * @author Romain DUBOIS
 */
public interface ITransport {

    /**
     * Get the transport ID.
     * 
     * @return The transport ID
     */
    String getId();

    /**
     * Test if transport layer is active.
     * 
     * @return If transport is active
     */
    boolean isActive();

    /**
     * Close the transport.
     */
    void close();

    /**
     * Get next incoming message.
     * 
     * @param pTime
     *            The timeout
     * @param pUnit
     *            The timeout unit
     * @return The next incoming message, or {@code null} if none came before
     *         timeout is reached
     * @throws InterruptedException
     *             If thread is interrupted
     * @throws RemoteException
     *             If a remote error occurred (transport layer problem)
     */
    Message receive(int pTime, TimeUnit pUnit) throws InterruptedException, RemoteException;

    /**
     * Send an invocation message.
     * 
     * @param pCallMessage
     *            The invocation message
     * @return The response message
     * @throws RemoteException
     *             If a remote error occurred (transport layer problem)
     */
    ResponseMessage call(InvocationMessage pCallMessage) throws RemoteException;

    /**
     * Send an invocation message.
     * 
     * @param pCallMessage
     *            The invocation message
     * @return The response message
     * @throws RemoteException
     *             If a remote error occurred (transport layer problem)
     */
    BlockingReference<ResponseMessage> asyncCall(InvocationMessage pCallMessage)
            throws RemoteException;

    /**
     * Send a message.
     * 
     * @param pMessage
     *            The message to send
     * @throws RemoteException
     *             If a remote error occurred (transport layer problem)
     */
    void send(Message pMessage) throws RemoteException;

    /**
     * Change the transport label (log usage).
     * 
     * @param pLabel
     *            The transport label
     */
    void setLabel(String pLabel);
}
